【Day 13】設定分離實務：ConfigMap 將環境變數與程式碼解耦

2026 iThome 鐵人賽

DAY 13

Kubernetes

從零開始的雲端實戰：30 天 Kubernetes 核心觀念與部署指南系列第 13 篇

18th鐵人賽

b132009

2026-08-25 10:35:26

143 瀏覽

分享至

今日目標

理解軟體架構中「設定（Config）與程式碼解耦」的核心原則（The Twelve-Factor App）。
搞懂 Kubernetes ConfigMap 的角色與應用情境。
掌握注入 ConfigMap 的兩大主流方式：環境變數（Environment Variables） 與 設定檔掛載（Volume Mount）。
實戰操作：建立 ConfigMap，並將其注入到 Pod 容器中進行讀取驗證。

痛點場景：為什麼不能把設定檔打包進 Image？

在傳統開發中，初學者常會把資料庫連線字串（如 localhost:3306）或環境名稱（如 dev / prod）直接寫死在程式碼中，或者直接打進 Docker Image。

這會帶來極大的維運災難：

重複打包 Image：每次只改一個連線 URL 或 Port，就必須重新 docker build 並推送到 Registry。
無法一套 Image 通用多環境：開發（Dev）、測試（Staging）、生產（Production）環境需要維護不同版本的 Image，失去容器「一次打包、到處運行」的初衷。

Kubernetes ConfigMap 正是為了實現**「程式碼與設定分離」**而生的關鍵物件。

核心思維：同一個 Docker Image，在 Dev 環境掛載 Dev ConfigMap；在 Prod 環境掛載 Prod ConfigMap，完全不需要重新建置映像檔！

ConfigMap 的核心結構

ConfigMap 本質上就是一個由 Key-Value（鍵值對） 組成的設定儲存庫。它的 Value 可以是：

單純的字串或純量（例如：APP_COLOR: blue）
完整的設定檔內容（例如：nginx.conf、application.properties 的整段文字）

實戰演練：ConfigMap 的兩種注入方式

方式一：將 ConfigMap 作為「環境變數（Env）」注入

這是最常見且最輕量的方式，適合簡單的設定參數。

步驟 1：建立 `app-config.yaml`

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-env-config
data:
  APP_ENV: "production"
  MAX_CONNECTIONS: "100"

步驟 2：在 Pod 中讀取 ConfigMap 環境變數

建立 pod-env.yaml，透過 valueFrom.configMapKeyRef 引入變數：

apiVersion: v1
kind: Pod
metadata:
  name: test-env-pod
spec:
  containers:
    - name: app
      image: busybox
      command: ["sh", "-c", "echo App is running in $APP_ENV mode with limit$MAX_CONNECTIONS; sleep 3600"]
      env:
        - name: APP_ENV
          valueFrom:
            configMapKeyRef:
              name: app-env-config
              key: APP_ENV
        - name: MAX_CONNECTIONS
          valueFrom:
            configMapKeyRef:
              name: app-env-config
              key: MAX_CONNECTIONS

步驟 3：套用並驗證 Log

kubectl apply -f app-config.yaml
kubectl apply -f pod-env.yaml

# 查看 Pod 印出的 log
kubectl logs test-env-pod

預期輸出：

App is running in production mode with limit 100

方式二：將 ConfigMap 作為「檔案（Volume）」掛載

當你的應用程式依賴特定的設定檔（例如 Nginx 的 default.conf 或 JSON 檔）時，直接掛載為檔案最為方便。

步驟 1：建立包含完整設定內容的 ConfigMap

建立 web-page-config.yaml：

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-index-config
data:
  index.html: |
    <!DOCTYPE html>
    <html>
    <head><title>K8s ConfigMap Demo</title></head>
    <body style="background-color: #f0f8ff; text-align: center; margin-top: 50px;">
      <h1>Hello from ConfigMap Mounted File!</h1>
      <p>This HTML content is injected from a Kubernetes ConfigMap dynamically.</p>
    </body>
    </html>

步驟 2：將 ConfigMap 掛載至 Nginx 靜態目錄

建立 nginx-config-pod.yaml：

apiVersion: v1
kind: Pod
metadata:
  name: nginx-custom-pod
spec:
  containers:
    - name: web
      image: nginx:1.25
      ports:
        - containerPort: 80
      volumeMounts:
        - name: html-volume
          mountPath: /usr/share/nginx/html # Nginx 預設網頁目錄
  volumes:
    - name: html-volume
      configMap:
        name: nginx-index-config # 對應 ConfigMap 名稱

步驟 3：套用並透過 Port-forward 查看效果

kubectl apply -f web-page-config.yaml
kubectl apply -f nginx-config-pod.yaml

# 建立本機端口轉發
kubectl port-forward pod/nginx-custom-pod 8080:80

打開瀏覽器訪問 http://localhost:8080，即可看到完全由 ConfigMap 動態注入的自訂 HTML 頁面！

踩坑紀錄：ConfigMap 不適合放什麼？

ConfigMap 雖然好用，但它完全沒有加密（資料全是以明文 Plaintext 儲存）。

絕對不要放：資料庫密碼、API 金鑰、TLS 憑證、私鑰。
正確做法：涉及敏感機密資訊時，應使用 Kubernetes 的 Secret 物件（我們將在第三週 Day 15 深入探討）。

本日小結

今天我們學會了如何使用 ConfigMap 讓「環境設定」與「映像檔」徹底解耦：

簡單參數可以用 env 注入為環境變數。
複雜設定檔可以用 volumeMounts 作為實體檔案掛載。

經過前面幾天的洗禮，我們已經掌握了 Deployment（運算）、Service & Ingress（網路）以及 ConfigMap（設定）。

明天 Day 14，我們要迎來第二週的總驗收實戰：「【實作】雙層架構部署：Web 前端 + 後端 API 在 K8s 上的通訊整合」！

【Day 12】流量總管：Ingress 與 Ingress Controller 網域路由設定

【Day 14】雙層架構部署：Web 前端 + 後端 API 在 K8s 上的通訊整合

系列文

從零開始的雲端實戰：30 天 Kubernetes 核心觀念與部署指南共 30 篇

RSS系列文訂閱系列文

2 人訂閱

完整目錄

熱門推薦

{{ item.channelVendor }} | {{ item.webinarstarted }} |

直播中

尚未有邦友留言

立即登入留言

參賽組數

624 組

團體組數

27 組

累計文章數

6914 篇

最後報名日

9/15

15th鐵人賽 16th鐵人賽 13th鐵人賽 14th鐵人賽 17th鐵人賽 12th鐵人賽 11th鐵人賽鐵人賽 2019鐵人賽 18th鐵人賽 javascript 2018鐵人賽 python 2017鐵人賽 windows php c# linux windows server css

IT邦幫忙

從零開始的雲端實戰：30 天 Kubernetes 核心觀念與部署指南系列 第 13 篇